<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>lindex manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> lindex</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
lindex &mdash; Retrieve an element from a list
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>lindex </B><I>list ?index ...?</I><BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
The <B>lindex</B> command accepts a parameter, <I>list</I>, which
it treats as a Tcl list. It also accepts zero or more <I>indices</I> into
the list.  The indices may be presented either consecutively on the
command line, or grouped in a
Tcl list and presented as a single argument.
<P>
If no indices are presented, the command takes the form:
<P>
<PRE><B>lindex </B><I>list</I></PRE>
<P>
or
<P>
<PRE><B>lindex </B><I>list</I> {}</PRE>
<P>
In this case, the return value of <B>lindex</B> is simply the value of the
<I>list</I> parameter.
<P>
When presented with a single index, the <B>lindex</B> command
treats <I>list</I> as a Tcl list and returns the
<I>index</I>'th element from it (0 refers to the first element of the list).
In extracting the element, <B>lindex</B> observes the same rules
concerning braces and quotes and backslashes as the Tcl command
interpreter; however, variable
substitution and command substitution do not occur.
If <I>index</I> is negative or greater than or equal to the number
of elements in <I>value</I>, then an empty
string is returned.
The interpretation of each simple <I>index</I> value is the same as
for the command <B><A HREF="../TclCmd/string.htm">string index</A></B>, supporting simple index
arithmetic and indices relative to the end of the list.
<P>
If additional <I>index</I> arguments are supplied, then each argument is
used in turn to select an element from the previous indexing operation,
allowing the script to select elements from sublists.  The command,
<P>
<PRE><B>lindex</B> $a 1 2 3</PRE>
<P>
or
<P>
<PRE><B>lindex</B> $a {1 2 3}</PRE>
<P>
is synonymous with
<P>
<PRE><B>lindex</B> [<B>lindex</B> [<B>lindex</B> $a 1] 2] 3</PRE>
<H3><A NAME="M5">EXAMPLES</A></H3>
Lists can be indexed into from either end:
<P>
<PRE><B>lindex</B> {a b c} 0
      <I><font size="+1">&rarr;</font> a</I>
<B>lindex</B> {a b c} 2
      <I><font size="+1">&rarr;</font> c</I>
<B>lindex</B> {a b c} end
      <I><font size="+1">&rarr;</font> c</I>
<B>lindex</B> {a b c} end-1
      <I><font size="+1">&rarr;</font> b</I></PRE>
<P>
Lists or sequences of indices allow selection into lists of lists:
<P>
<PRE><B>lindex</B> {a b c}
      <I><font size="+1">&rarr;</font> a b c</I>
<B>lindex</B> {a b c} {}
      <I><font size="+1">&rarr;</font> a b c</I>
<B>lindex</B> {{a b c} {d e f} {g h i}} 2 1
      <I><font size="+1">&rarr;</font> h</I>
<B>lindex</B> {{a b c} {d e f} {g h i}} {2 1}
      <I><font size="+1">&rarr;</font> h</I>
<B>lindex</B> {{{a b} {c d}} {{e f} {g h}}} 1 1 0
      <I><font size="+1">&rarr;</font> g</I>
<B>lindex</B> {{{a b} {c d}} {{e f} {g h}}} {1 1 0}
      <I><font size="+1">&rarr;</font> g</I></PRE>
<P>
List indices may also perform limited computation, adding or subtracting fixed
amounts from other indices:
<P>
<PRE>set idx 1
<B>lindex</B> {a b c d e f} $idx+2
      <I><font size="+1">&rarr;</font> d</I>
set idx 3
<B>lindex</B> {a b c d e f} $idx+2
      <I><font size="+1">&rarr;</font> f</I></PRE>
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/list.htm">list</A></B>, <B><A HREF="../TclCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TclCmd/linsert.htm">linsert</A></B>, <B><A HREF="../TclCmd/llength.htm">llength</A></B>, <B><A HREF="../TclCmd/lsearch.htm">lsearch</A></B>, <B><A HREF="../TclCmd/lset.htm">lset</A></B>, <B><A HREF="../TclCmd/lsort.htm">lsort</A></B>, <B><A HREF="../TclCmd/lrange.htm">lrange</A></B>, <B><A HREF="../TclCmd/lreplace.htm">lreplace</A></B>, <B><A HREF="../TclCmd/string.htm">string</A></B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/E.htm#element">element</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/L.htm#list">list</A>
<div class="copy">Copyright &copy; 1993 The Regents of the University of California.
<BR>Copyright &copy; 1994-1996 Sun Microsystems, Inc.
<BR>Copyright &copy; 2001 Kevin B. Kenny &lt;kennykb(at)acm.org&gt;. All rights reserved.
</div>
</BODY></HTML>
